home *** CD-ROM | disk | FTP | other *** search
/ Software Vault: The Gold Collection / Software Vault - The Gold Collection (American Databankers) (1993).ISO / cdr49 / 274_01.zip / ARRAY.DOC < prev    next >
Text File  |  1993-04-01  |  13KB  |  377 lines
  1. Array Handling Package
  2. (C) Copyright 1985,1987,1988 James P. Cruse - All Rights Reserved
  3.  
  4. Array.doc
  5.  
  6. Version 1.00
  7.  
  8. This set of C header files is used to simplify array handling in C.
  9.  
  10. Included are routines to add, subtract, fill, negate, and get info on 
  11. arrays. See Complete Descriptions of functions below.
  12.  
  13. First, the Legal Issues:
  14.  
  15.  
  16. The routines are copyrighted by the author, and have been released as a
  17. user supported program. You may use this program on a trial basis, and if 
  18. you find it to be useful, or you continue using it, you must register it.
  19. Any Commercial enterprises using this software must register it immediately.
  20. You may not include the Source code of these routines with any 
  21. commercial package without written consent of the author. You may use 
  22. them to develop commercial programs upon registration.
  23. Simple registration of these routines is $10.00. If you wish to recieve 
  24. an upgrade of the routines, and trial usage of the STAT and function 
  25. equivalents, the registration fee is $25.00. To recieve a copy of the 
  26. Scientific Functions is $50.00. (See Description below).
  27.  
  28. Registration should be mailed to:
  29.  
  30.     James P. Cruse
  31.     919 Capitola Avenue
  32.     Suite 41
  33.     Capitola, CA 95010
  34.     (408) 475-7444 (m)
  35.  
  36.  
  37. I am currently developing other routines for C, as well as improving
  38. these. Routines that I am developing include: integer, float, and
  39. "user" defined functions (not macros) that are equivalent to these routines;
  40. Simple Statistical functions (mean,median,mode,r^2,s^2,standard deviation);
  41. Scientific Functions (polynomials, curve fits, convolutions); and
  42. Plotting routines for the IBM PC/XT/AT and compatibles (routines to plot on
  43. screen, printer or HP plotter x-y plots of up to 16 parameters in a 4
  44. windows).
  45.  
  46.  
  47. Back to the routines:
  48.  
  49.  
  50. The routines are broken up into the following types:
  51.  
  52. Binary Operations    Add, Subtract, Multiply, etc. between 2 arrays
  53. Unary Operations    Negate, Assign, absolute, etc. an array
  54. Fill Operations        Fill array with index, index+off, values between x&y
  55. Info about Array    Min, Max, etc of an array
  56.  
  57. There are also routines to call a function on 1 or 2 arrays.
  58.  
  59. The routines work by substituting your call into a while loop. This was the 
  60. ONLY way I could find to use different types of arrays/constants in an 
  61. expression that would be compatible across a wide range of compilers/systems. 
  62. (I spent 3 months trying all kinds of different ways, but none would 
  63. work on ALL of the compilers I could test with, except this method).
  64.  
  65. The Functions all have a uniform naming format:
  66.  
  67.     X_NAME, where X is a, for single array operations, aa for 
  68.         2 array, ac for array & constant, and ca for contant & array
  69.         And NAME is the operation to be done. For Example:
  70.  
  71.         aa_add()    add two arrays
  72.         ac_add()    add array & constant
  73.         a_neg()        negate array
  74.         a_index()    fill array with index
  75.  
  76. They also have a uniform parameter format:
  77.  
  78. X_NAME(s,d,...)    where s is length of array, d is destination array, and
  79.     "..." varies for each type of operation,
  80.     a,b are arrays, c is a constant:
  81.         Binary operations have 2 parameters, a and b or a and c
  82.         Unary operations have a single parameter a
  83.         info operations have a single parameter
  84.         and fill operations take multiple parameters.
  85.  
  86.     The function can also take other parameters, depending on the 
  87.     operation. 
  88.  
  89. See the file array.h for customization options. In order to use the
  90. functions, place all the .h files in your include directory, and 
  91. include the file "array.h". This will load in the files you have 
  92. defaulted to be loaded. See array.h for further details.
  93.  
  94. I also include 3 Test Files, a_testall.c, a_testf.c and a_testi.c.
  95. They test the various functions. a_testf does a floating point test,
  96. a_testi does an integer test, and a_testall.c tests All of the routines.
  97. NOTE: due to roundoff errors, and floating compare for equality, the
  98. a_testall may not compare properly for Floats or Doubles. 
  99.  
  100.  
  101. I recommend looking at a_testi or a_testf for examples on how to code
  102. using these algorithms, as a_testall is a large testing program with 
  103. little basis in reality.
  104.  
  105. The routines have been tested with multiple compilers including Microsoft
  106. 5.0, Turbo 1.5 and Aztec 3.40B all on a PC Clone.
  107.  
  108.  
  109.  
  110. The following is a quick description of the operations available. 
  111. Remember to prepend the a_,aa_,ac_,ca_ to the name depending on
  112. the parameters to the operation. Each list is followed by an example
  113. of a couple of the functions. For more information, see the list
  114. at the end of the file to get a list of Every function.
  115.  
  116. Binary Operations: (a_binop.h)
  117.     add, sub, mul, div, min, max, mod (%,modulo),
  118.     equ (==), geq (>=), leq (<=), gtr (>), les (<),
  119.     fun (function), t_fun (typed function)
  120.  
  121.     aa_add(n,d,a,b)        d[] = a[] + b[]
  122.     ac_min(n,d,a,c)        d[] = ARR_MIN(a[],c)
  123.     ca_sub(n,d,c,a)        d[] = c - a[]
  124.  
  125.     aa_fun(n,d,a,b,f)    d[] = f(a[],b[])
  126.     ac_t_fun(n,d,a,c,f,t)    d[] = f( (t) a[] , (t) c )
  127.  
  128.  
  129. Unary Operations: (a_unop.h)
  130.     cpy (copy,assign), neg (negate), abs (absolute value), 
  131.     rsum (running sum), rprod (running product),
  132.     rmin (running min), rmax (running max),
  133.     fun (function), t_function (typed function)
  134.     scale (scale&offset)
  135.  
  136.     a_cpy(n,d,a)        d[] = a[] 
  137.     a_rsum            d[i] = d[i-1] + a[i]
  138.     a_rmax            d[i] = ARR_MAX( d[i-1] , a[i] )
  139.  
  140.     a_scale(n,d,a,s,o)    d[] = o + s*a[]
  141.  
  142.     a_fun(n,d,a,f)        d[] = f(a[]])
  143.     a_t_fun(n,d,a,f,t)    d[] = (t) f( (t) a[] )
  144.  
  145.  
  146. Fill Operations: (a_fill.h)
  147.     NOTE: please see the discussion in a_fill.h for details concerning
  148.     the different versions of fill.
  149.  
  150.     index, indoff (index+offset), fill (exclusive), 
  151.     ifill (inclusive), t_fill (typed fill), t_ifill (typed inc. fill)
  152.     scale (scale&offset), 
  153.     assign, f_fun (function), i_fun, (function w/index param),
  154.     t_i_fun (typed function w/index param)
  155.  
  156.     a_indoff(n,d,c)        d[i] = i + c
  157.     a_assign(n,d,c)        d[] = c
  158.     a_i_scale(n,d,s,o)    d[i] = s*i + o
  159.  
  160.     a_fill(n,d,s,e)        d[0] = s, d[i] = s+(e-s)/n, d[n] (would be) e 
  161.     a_t_ifill(n,d,s,e)    d[0] = s, d[i] = s+((t)(e-s))/(n-1), d[n-1] = e
  162.  
  163.     a_f_fun(n,d,f)        d[] = f()
  164.     a_t_i_fun(n,d,f,t)    d[i] = f( (t) i )
  165.  
  166.  
  167. Info Operations: (a_info.h)
  168.     sum, prod, min, max, minmax
  169.  
  170.     a_sum(n,d,a)        d = a[0] + a[1] + ... + a[n-1]
  171.     a_min(n,d,a)        d = min( a[0] , a[1] , ... , a[n-1] )
  172.     a_minmax(n,l,u,a)    l = min( a[0] , a[1] , ... , a[n-1] ),
  173.             and    u = max( a[0] , a[1] , ... , a[n-1] )
  174.  
  175.  
  176.  
  177.  
  178. COMPLETE SUMMARY LIST OF FUNCTIONS:
  179.  
  180.  
  181. Notation:
  182.     d    =>    destination parameter d - a constant
  183.     d[]    =>    all elements of array d (from 0 to n-1)
  184.     d[i]    =>    the i'th element of array d (from 0 to n-1)
  185.     d[i-1]    =>    the i-1'th element of array d (from 1 to n-1)
  186.     a[+]    =>    all elements of a[] are "+"'ed (sum of a[])
  187.     s    =>    parameter s
  188.     f()    =>    function parameter f (i.e. cos)
  189.     T    =>    function type T (i.e. float)
  190.  
  191.     running "sums" are d[0] = a[0], d[1] = d[0] "+" a[1], ...
  192.         d[n-2] = d[n-3] "+" a[n-2], d[n-1] = d[n-2] "+" a[n-1]
  193.  
  194.  
  195. BINARY OPERATIONS:
  196.  
  197. Note:
  198.     for each operation, there are 3 macros, for each combination
  199.         of arrays and constants, for example:
  200.         aa_op(n,d,a,b)     array, array operation      (d[] = a[] + b[])
  201.         ac_op(n,d,a,c)    array, constant operation (d[] = a[] * c)
  202.         ca_op(n,d,c,a)    constant, array operation (d[] = c - a[])
  203.  
  204. The functions are: 
  205.     aa_add(n,d,a,b)    d[] = a[] + b[]        add a[] and b[]
  206.     ac_add(n,d,a,c)    d[] = a[] + c          add a[] and c  
  207.     ca_add(n,d,c,b)    d[] = c   + b[]        add c and b[]
  208.  
  209.     aa_sub(n,d,a,b)    d[] = a[] - b[]        sub b[] from a[]
  210.     ac_sub(n,d,a,c)    d[] = a[] - c          sub c from b[]
  211.     ca_sub(n,d,c,b)    d[] = c   - b[]        sub b[] from c
  212.  
  213.     aa_mul(n,d,a,b)    d[] = a[] * b[]        multiply a[] and b[]
  214.     ac_mul(n,d,a,c)    d[] = a[] * c          multiply a[] and c
  215.     ca_mul(n,d,c,b)    d[] = c   * b[]        multiply c and b[]
  216.  
  217.     aa_div(n,d,a,b)    d[] = a[] / b[]        divide a[] by b[]
  218.     ac_div(n,d,a,c)    d[] = a[] / c          divide a[] by c
  219.     ca_div(n,d,c,b)    d[] = c   / b[]        divide c by a[]
  220.  
  221.     aa_mod(n,d,a,b)    d[] = a[] % b[]        Modulo a[] by b[]
  222.     ac_mod(n,d,a,c)    d[] = a[] % c          Modulo a[] by c
  223.     ca_mod(n,d,c,b)    d[] = c   % b[]        Modulo c by a[]
  224.  
  225.     aa_max(n,d,a,b)    d[] = ARR_MAX(a[],b[])    max of a[] and b[]
  226.     ac_max(n,d,a,c)    d[] = ARR_MAX(a[],c)    max of a[] and c
  227.     ca_max(n,d,c,b)    d[] = ARR_MAX(c,b[])    max of c and b[]
  228.  
  229.     aa_min(n,d,a,b)    d[] = ARR_MIN(a[],b[])    min of a[] and b[]
  230.     ac_min(n,d,a,c)    d[] = ARR_MIN(a[],c)    min of a[] and c
  231.     ca_min(n,d,c,b)    d[] = ARR_MIN(c,b[])    min of c and b[]
  232.  
  233.     aa_equ(n,d,a,b)    d[] = a[] == b[]    a[] equal b[]
  234.     ac_equ(n,d,a,c)    d[] = a[] == c      a[] equal c
  235.     ca_equ(n,d,c,b)    d[] = c   == b[]    c equal b[]
  236.  
  237.     aa_geq(n,d,a,b)    d[] = a[] >= b[]    a[] greater than or equal b[]
  238.     ac_geq(n,d,a,c)    d[] = a[] >= c      a[] greater than or equal c
  239.     ca_geq(n,d,c,b)    d[] = c   >= b[]    c   greater than or equal b[]
  240.  
  241.     aa_gtr(n,d,a,b)    d[] = a[] >  b[]    a[] greater than b[]
  242.     ac_gtr(n,d,a,c)    d[] = a[] >  c      a[] greater than c
  243.     ca_gtr(n,d,c,b)    d[] = c   >  b[]    c   greater than b[]
  244.  
  245.     aa_leq(n,d,a,b)    d[] = a[] <= b[]    a[] less than or equal b[]
  246.     ac_leq(n,d,a,c)    d[] = a[] <= c      a[] less than or equal c
  247.     ca_leq(n,d,c,b)    d[] = c   <= b[]    c   less than or equal b[]
  248.  
  249.     aa_les(n,d,a,b)    d[] = a[] <  b[]    a[] less than b[]
  250.     ac_les(n,d,a,c)    d[] = a[] <  c      a[] less than c
  251.     ca_les(n,d,c,b)    d[] = c   <  b[]    c   less than b[]
  252.  
  253.     aa_fun(n,d,a,b,f())            call f on a[] and b[]
  254.             d[] = f( a[] , b[] )
  255.     ac_fun(n,d,a,c,f())            call f on a[] and c
  256.             d[] = f( a[] , c )
  257.     ca_fun(n,d,c,b,f())            call f on c and a[]
  258.             d[] = f( c , a[] )
  259.  
  260.     aa_t_fun(n,d,a,b,f(),T)            call f on a[] and b[]
  261.             d[] = f((T)a[],(T)b[])    forcing a[i],b[i] to type T
  262.     ac_t_fun(n,d,a,c,f(),T)            call f on a[] and c
  263.             d[] = f( (T)a[], (T)c )    forcing a[i],c to type T
  264.     ca_t_fun(n,d,c,b,f(),T)            call f on c and a[]
  265.             d[] = f( (T)c, (T)a[] )    forcing c,a[i] to type T
  266.  
  267.  
  268. UNARY OPERATIONS:
  269.  
  270.     a_cpy(n,d,a)    d[] = a[];              copy a to d
  271.  
  272.     a_neg(n,d,a)    d[] = - a[];        negate a to d
  273.  
  274.     a_abs(n,d,a)    d[] = ARR_ABS(a[])    absolute value of a to d
  275.  
  276.     a_scale(n,d,a,s,o)            scale & offset of a to d
  277.             d[] = o + s*a[]        => linear poly of a to d
  278.  
  279.     a_rsum(n,d,a)    d[i] = d[i-1] + a[i]    running sum of a to d
  280.  
  281.     a_rprod(n,d,a)    d[i] = d[i-1] * a[i]    running sum of a to d
  282.  
  283.     a_rmin(n,d,a)    d[i] = ARR_MIN(d[i-1],d[i])
  284.                         running minimum of a to d
  285.  
  286.     a_rmax(n,d,a)    d[i] = ARR_MAX(d[i-1],d[i])
  287.                         running maximum of a to d
  288.  
  289.     a_fun(n,d,a,f())            call function f on a to d
  290.             d[i] = f ( a[i] )    
  291.  
  292.     a_t_fun(n,d,a,f(),T)            call function f on a to d
  293.             d[i] = f ( (T)a[i] )    forcing a to type T
  294.  
  295.  
  296. FILL OPERATIONS:
  297.  
  298.     a_index(n,d)    d[i] = i        index
  299.  
  300.     a_indoff(n,d,o)    d[i] = o + i        index + offset
  301.  
  302.     a_assign(n,d,c)    d[] = c            assign constant to d[]
  303.  
  304.     a_i_scale(n,d,s,o)            scale with index
  305.             d[i] = o + i*s        linear poly on index
  306.  
  307.     a_fill(n,d,b,e)    d[i] = b + i*((e-b)/n)    exclusive fill
  308.                 d[0] = b, d[n] would be e
  309.  
  310.     a_ifill(n,d,b,e) d[i] = b + i*((e-b)/(n-1) inclusive fill
  311.                 d[0] = b, d[n-1] = e
  312.  
  313.     a_t_fill(n,d,b,e,T)            typed exclusive fill
  314.             d[i] = b + (T)i*(((T)(e-b))/(n))
  315.  
  316.     a_t_ifill(n,d,b,e,T)            typed inclusive fill
  317.             d[i] = b + (T)i*(((T)(e-b))/(n-1))
  318.  
  319.     a_f_fun(n,d,f()) d[] = f()        fill with return of function
  320.  
  321.     a_i_fun(n,d,f()) d[i] = f(i)        function fill with index parm
  322.  
  323.     a_t_i_fun(n,d,f(),T) d[i] = f( (T)i )    typed function fill, type index
  324.  
  325.  
  326. Note:
  327.     the various fill behave somewhat non-intuitivally due to using
  328.     integers as index. The following examples should clear up the 
  329.     differences. f is a float destination array, i is the index, b = 1,
  330.     and e = 10
  331.                            f(x)
  332. call:        rval:i=>   0    1    3      5        8          9
  333.  
  334. a_fill(10,f,0,10)    => 0  1.000000  3.000000  5.000000  8.000000  9
  335. a_ifill(10,f,0,10)    => 0  1.000000  3.000000  5.000000  8.000000  10
  336. a_t_fill(10,f,0,10,float)  0  1.000000  3.000000  5.000000  8.000000  9
  337. a_t_ifill(10,f,0,10,float) 0  1.111111  3.333333  5.555555  8.888889  10
  338. a_fill(10,f,0.0,10.0)       0  1.000000  3.000000  5.000000  8.000000  9
  339. a_ifill(10,f,0.0,10.0)       0  1.111111  3.333333  5.555555  8.888889  10
  340.  
  341. What this all means is two things: 
  342. 1> if you do not type the fill to a float or use a float b or e parameter, 
  343. the numbers you get back may not be what you expect. 
  344. 2> The difference between fill and ifill is whether or not the last 
  345. index is going to be exactly the end point or not:
  346.     d[n-1] = b + (n-1)*(e-b)/(n-1)     => e         in ifill
  347.     d[n-1] = b + (n-1)*(e-b)/n     => e - (e-b)/n     in fill.
  348.  
  349.  
  350.  
  351. INFORMATION OPERATIONS
  352.  
  353.     a_sum(n,d,a)    d = a[+]        sum of array
  354.  
  355.     a_prod(n,d,a)    d = a[*]        product of array
  356.  
  357.     a_max(n,d,a)    d = max(a[])        max value in array
  358.  
  359.     a_min(n,d,a)    d = min(a[])        min value in array
  360.  
  361.     a_minmax(n,l,u,a)            min and max of array
  362.             l = min(a[]), u = max(a[])
  363.  
  364.  
  365.  
  366.  
  367. Thats all the functions for now. If you have any questions, or would
  368. like to register, please feel free to call or write me.
  369.  
  370.             James P. Cruse
  371.             919 Capitola Ave #41
  372.             Capitola, CA 95010
  373.             (408) 475-7444 (h,m)
  374.  
  375.  
  376.  
  377.